home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / README < prev   
Encoding:
Text File  |  1995-11-02  |  11.1 KB  |  260 lines  |  [TEXT/MPS ]
  1. This is version 2.7 of ``noweb'', a simple, extensible literate-
  2. programming tool.  noweb is available via anonymous ftp from the
  3. Comprehensive TeX Archive Network, in directory web/noweb.  CTAN
  4. includes hosts ftp.shsu.edu, ftp.tex.ac.uk, and ftp.uni-stuttgart.de.
  5. Note that if you simply get 'noweb.tgz', you'll be getting a bunch of
  6. binary distributions that you probably don't want.  Most users will
  7. want either one of the binary distributions or else the source (src).
  8. Fanatics can check out the contrib and examples directories.
  9.  
  10. The CTAN sites mirror the master directory bellcore.com:pub/norman/noweb.
  11. You can also get the master tar file bellcore.com:pub/norman/noweb-2.7.tgz, 
  12. which contains source, contributed software, and examples, but no binaries.
  13.  
  14. To build noweb, change to the `src' directory and follow the
  15. instructions in the file INSTALL.
  16.  
  17.  
  18. WHAT'S NEW IN VERSION 2.7
  19.  
  20. This version includes support for converting LaTeX to HTML and support
  21. for parsing nuweb files.  So, if you want an HTML version of a nuweb
  22. program, try this:
  23.    noweave -markup numarkup -filter l2h -html -index mumble.w > mumble.html
  24. This version also has a more liberal copyright, some bug fixes, an
  25. updated Hacker's Guide, and another useful new filter, elide.  For
  26. details see the CHANGES file.
  27.  
  28. Also, DIRECTORY LAYOUT AND INSTALLATION INSTRUCTIONS HAVE CHANGED.
  29.  
  30. My testing of the awk versions of the filters was cursory.
  31. I welcome bug reports.
  32.  
  33.  
  34. INTRODUCTION --- WHAT IS NOWEB, ANYWAY?
  35.  
  36. noweb is designed to meet the needs of literate programmers while
  37. remaining as simple as possible.  Its primary advantages are
  38. simplicity, extensibility, and language-independence.  noweb uses 5
  39. control sequences to WEB's 27.  The noweb manual is only 3 pages; an
  40. additional page explains how to customize its LaTeX output.  noweb
  41. works ``out of the box'' with any programming language, and supports
  42. TeX, latex, and HTML (Mosaic) back ends.  A back end to support full
  43. hypertext or indexing takes about 250 lines; a simpler one can be
  44. written in 40 lines of awk.  The primary sacrifice relative to WEB is
  45. that code is not prettyprinted.
  46.  
  47. noweb has been used for five years both at Princeton and elsewhere.
  48. It has been used for tens of thousands of lines of code in such
  49. languages as awk, C, C++, Icon, Modula-3, PAL, perl, Promela, and
  50. Standard ML.
  51.  
  52. If you already know you want to use noweb, you need only install it
  53. and read the manual page.  If you're just curious about noweb, read
  54. the paper that appeared in the September 1994 issue of IEEE Software.
  55. If you can't get Software, send me a postcard and I'll send you a
  56. reprint. 
  57.  
  58. If you're brand new to literate programming, check out the FAQ for the
  59. USENET newsgroup comp.programming.literate.   There are also some
  60. resources available through the noweb home page:
  61.    ftp://bellcore.com/pub/norman/www/noweb/intro.html
  62.  
  63.  
  64. WHAT YOU GET IN THIS DISTRIBUTION
  65.  
  66. This distribution contains the following directories:
  67.   binaries    Pre-built distributions containing binaries and documentation
  68.   contrib    software contributed by noweb users 
  69.   examples    sample noweb filters and programs in different languages
  70.   src        Source code and documentation for noweb
  71. Where appropriate, these directories have README files of their own.
  72. BINARY DISTRIBUTIONS MAY NOT ALWAYS BE UP-TO-DATE, especially DOS
  73. distributions.
  74.   
  75.  
  76. EXTENSIBILITY
  77.  
  78. noweb provides extensibility by using the Unix toolkit philosophy.
  79. The ``noweb,'' ``notangle,'' and ``noweave'' commands are built from
  80. pieces, which are then assembled in pipelines using shell scripts.
  81. The pieces include:
  82.  
  83.   markup    convert noweb file from human syntax to tool syntax
  84.   unmarkup    inverse of markup
  85.   totex        convert from tool syntax to TeX/latex markup
  86.   tohtml    convert from tool syntax to HTML markup
  87.   nt        `tangle' the tool form of the noweb file
  88.   mnt        discover roots, then act like nt
  89.   noidx        insert indexing and cross-reference information
  90.   finduses    finds uses of identifiers
  91.  
  92. These pieces are combined by the scripts in the src/shell directory to
  93. provide more than just weaving and tangling:
  94.  
  95.   noweb        analog of nuweb
  96.   notangle    analog of TANGLE
  97.   noweave    analog of WEAVE
  98.   nountangle    tangle, but keep interleaved documentation in comments
  99.   noroots    print names of all root chunks in a noweb file
  100.   nocount    count number of lines of code and documentation.
  101.   nodefs    extract defined identifiers for noweave -indexfrom
  102.   noindex    build an external index for multi-file documents
  103.  
  104.  
  105. WEAVING --- A TAR PIT
  106.  
  107. The worst aspect of literate programming is the enormous amount of
  108. time wasted wrangling over what ``woven'' output should look like.
  109. Although noweb does no prettyprinting, it is not entirely immune---
  110. several people have complained about noweave's output or have sent me
  111. changes that add more options to noweave.  I resisted for years, but
  112. with version 2.5 I finally succumbed.  I let the number of options to
  113. noweave double, and I have provided for too many options and hooks for
  114. customizing the latex output.  I won't let it happen again.
  115.  
  116. noweb doesn't try to be all things to all programmers, but it is very
  117. easy to change.  If you don't like noweave's formatting, you can read
  118. tex/support.nw to learn how to customize it; look for the words
  119. ``style hook.''  (Reading noweb.sty directly is not recommended.)  For
  120. simple formatting, it might be easier to throw away noweave and make
  121. your own.  To help you get started, the shell directory contains
  122. noweave.simple, a simplified version of noweave that Dave Hanson
  123. created for use with C programs (it can't handle code with @ signs).
  124. The Noweb Hacker's Guide (xdoc/guide.tex) explains the intermediate
  125. language that noweb uses to represent literate programs.
  126.  
  127. The intermediate language makes it possible to extend noweave with a
  128. language-dependent prettyprinter, as shown by contributions of an Icon
  129. prettyprinter by Kostas Oikonomou and a guarded-command prettyprinter
  130. by Conrado Martinez-Parra.  (I haven't written a prettyprinter myself
  131. because my experience with Spider taught me that prettyprinting is far
  132. more trouble than it's worth.)  Further contributions of
  133. prettyprinters are welcome.
  134.  
  135. noweb comes with two cross-referencers for use with noweave.  The
  136. standard one is written in Icon, because Icon offers excellent
  137. functionality and performance.  Because Icon is not available on all
  138. platforms, I profide an alternative, but inferior cross-referencer
  139. written in awk.  See the INSTALL file for details.
  140.  
  141. Cross-referencing makes formatting even more of a tar pit; the
  142. cross-referencer itself takes about 300 lines, and extensive LaTeX
  143. support is also required.  I haven't made the attempt to write
  144. cross-reference code for plain TeX.  Anyone who has ideas for reducing
  145. the number of options or for other ways to restore sanity to the
  146. situation is urged to write to norman@bellcore.com.
  147.  
  148.  
  149. INDEX AND IDENTIFIER CROSS-REFERENCE
  150.  
  151. To noweb, any string of nonwhite characters can be an identifier.  A
  152. human being or a language-dependent tool must mark definitions of
  153. identifiers; noweb finds the uses using a language-independent
  154. algorithm.  The algorithm relies on an idea taken from the lexical
  155. conventions of Standard ML.  Characters are divided into three
  156. classes: alphanumerics, symbols, and delimiters.  If an identifier
  157. begins with an alphanumeric, it must be delimited on the left by a
  158. symbol or a delimiter.  If it begins with a symbol, it must be
  159. delimited on the left by an alphanumeric or a delimiter.  If it begins
  160. with a delimiter, there are no restrictions on the character
  161. immediately to the left.  Similar rules apply on the right-hand side.
  162. The default classifications are chosen to make sense for commonly used
  163. programming languages, so that noweb will not recognize `zip' when it
  164. sees `zippy', or `++' when it sees `++:='.  This trick works
  165. surprisingly well, but it does not prevent noweb from spotting
  166. identifiers in comments or string literals.
  167.  
  168. The basic assumption in noweb is that a human being will identify
  169. definitions using the
  170. @ %def mumble foo quux
  171. construct.  I have, however, found it very useful to write simple
  172. filters that attempt to identify global definitions automatically.
  173. Filters for Icon, TeX, and yacc all take about 30 lines of Icon code
  174. and are included in the noweb distribution.  Contributions for other
  175. languages are encouraged.  If you write a filter of your own, you can
  176. put it in the $LIB directory with a name like `autodefs.pascal'.
  177.  
  178. noweave -index works well for short programs, but nodefs, noindex, and
  179. noweave -indexfrom are there for large multi-file programs.  See the
  180. noindex man page for details.
  181.  
  182.  
  183. NOTES
  184.  
  185.   src/xdoc/techrep.* contains an early, almost unrecognizable version
  186.   of a paper describing noweb that appeared in IEEE Software in
  187.   September, 1994.  You are probably better off writing me for a
  188.   reprint of the Software paper.  (Send a postcard!)
  189.  
  190.   The Noweb Hacker's Guide, which appears in src/xdoc/guide.*,
  191.   documents the representation of noweb files that is used by the
  192.   noweb tools, in case you want to write any tools of your own.
  193.   Simple tools (e.g. count the number of lines of interleaved
  194.   documentation) are trivial.  If you write any tools, or you want
  195.   tools written (e.g. prettyprinters, index generators), let me know.
  196.  
  197.   The icon directory contains Icon versions of most pipeline
  198.   stages.  If you want to adapt noweb to work with a text processor
  199.   other than TeX or latex, they might provide a better starting point.
  200.   Perhaps the whole system should have been written in Icon from the
  201.   beginning, but I'm not going to do it over.  Icon is available by
  202.   anonymous ftp from cs.arizona.edu.
  203.  
  204.   I have a standing offer open to troff users: I will adapt noweb to
  205.   troff if you will tell me what the output should look like and you
  206.   will try to use the results.
  207.   
  208.   Thanks to Preston Briggs for the Aho-Corasick recognizer, and for
  209.         helpful discussions.
  210.   Thanks to Dave Hanson for cpif.
  211.   Thanks to Dave Love for LaTeX wizardry.
  212.   Thanks to Joseph Reynolds for prodding me to fix [[...]].
  213.   Thanks to Bill Trost for the original HTML back end.
  214.   Thanks to Lee Wittenberg for the DOS binaries.
  215.  
  216. Send comments or questions to norman@bellcore.com.  
  217.  
  218. I enjoy hearing from noweb users; if you have enjoyed noweb, why not
  219. send me a local postcard for my collection?  My address is:
  220.  
  221.   Norman Ramsey
  222.   Bellcore
  223.   445 South Street
  224.   Morristown, New Jersey 07960
  225.                USA
  226.  
  227.  
  228. COPYRIGHT
  229.  
  230. Noweb is copyright 1989-1995 by Norman Ramsey.  All rights reserved.
  231.  
  232. Welcome to noweb for MPW!
  233.  
  234. This is a first snapshot of my port of noweb to MPW. To run it, you additionally
  235. need the MacPerl 5.0.1r1m or later MPW tool, available from
  236.  
  237. ftp://ftp.switch.ch/software/mac/perl
  238. ftp://ftp.share.com/pub/macperl
  239.  
  240. l2h, the HTML markup tool, was built using icon, available from
  241.  
  242. ftp://ftp.arizona.edu/pub/icon
  243.  
  244. Please report bugs to me
  245.  
  246. Matthias Neeracher
  247. neeri@iis.ee.ethz.ch
  248.  
  249. ----------------
  250.  
  251. You may use and distribute noweb for any purpose, for free.  You may
  252. modify noweb and create derived works, provided you retain the
  253. copyright notice, but the result may not be called noweb without my
  254. written consent.  You may not sell noweb itself, but you may do
  255. anything you like with programs created with noweb.
  256.  
  257. Noweb is not a Bellcore product.  Bellcore makes no warranty and
  258. accepts no liability for any software in this distribution.  If you
  259. find something useful, we're all surprised.
  260.